home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 2.iso / dist / fw_libmikmod.idb / usr / freeware / info / mikmod.info-2.z / mikmod.info-2
Text File  |  2000-06-09  |  50KB  |  1,809 lines
  1. This is mikmod.info, produced by Makeinfo version 3.12f from
  2. mikmod.texi.
  3.  
  4.    Copyright (C) 1998, 1999, 2000 Miodrag Vallat and others -- see file
  5. AUTHORS for complete list.
  6.  
  7.    This library is free software; you can redistribute it and/or modify
  8. it under the terms of the GNU Library General Public License as
  9. published by the Free Software Foundation; either version 2 of the
  10. License, or (at your option) any later version.
  11.  
  12.    This program is distributed in the hope that it will be useful, but
  13. WITHOUT ANY WARRANTY; without even the implied warranty of
  14. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15. Library General Public License for more details.
  16.  
  17.    You should have received a copy of the GNU Library General Public
  18. License along with this library; if not, write to the Free Software
  19. Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  20. USA.
  21.  
  22. INFO-DIR-SECTION Programming
  23. START-INFO-DIR-ENTRY
  24. * MikMod: (mikmod).            MikMod Sound Library.
  25. END-INFO-DIR-ENTRY
  26.  
  27. 
  28. File: mikmod.info,  Node: Error Reference,  Next: Function Reference,  Prev: Structure Reference,  Up: Library Reference
  29.  
  30. Error Reference
  31. ===============
  32.  
  33.    The following errors are currently defined:
  34.  
  35. General Errors
  36. --------------
  37.  
  38. `MMERR_DYNAMIC_LINKING'
  39.      This error occurs when a specific driver was requested, but the
  40.      support shared library couldn't be loaded. Currently, the only
  41.      drivers which can yield this error are the ALSA, EsounD and Ultra
  42.      drivers.
  43.  
  44. `MMERR_OPENING_FILE'
  45.      This error occurs when a file can not be opened, either for read
  46.      access from a `xx_Loadxx' function, or for write access from the
  47.      disk writer drivers.
  48.  
  49. `MMERR_OUT_OF_MEMORY'
  50.      This error occurs when there is not enough virtual memory
  51.      available to complete the operation, or there is enough memory but
  52.      the calling process would exceed its memory limit. MikMod does not
  53.      do any resource tuning, your program has to use the `setrlimit'
  54.      function to do this if it needs to load very huge samples.
  55.  
  56. Sample Errors
  57. -------------
  58.  
  59. `MMERR_SAMPLE_TOO_BIG'
  60.      This error occurs when the memory allocation of the sample data
  61.      yields the error `MMERR_OUT_OF_MEMORY'.
  62.  
  63. `MMERR_OUT_OF_HANDLES'
  64.      This error occurs when your program reaches the limit of loaded
  65.      samples, currently defined as 384, which should be sufficient for
  66.      most cases.
  67.  
  68. `MMERR_UNKNOWN_WAVE_TYPE'
  69.      This error occurs when you're trying to load a sample which format
  70.      is not recognized.
  71.  
  72. Module Errors
  73. -------------
  74.  
  75. `MMERR_ITPACK_INVALID_DATA'
  76.      This error occurs when a compressed module sample is corrupt.
  77.  
  78. `MMERR_LOADING_HEADER'
  79.      This error occurs when you're trying to load a module which has a
  80.      corrupted header, or is truncated.
  81.  
  82. `MMERR_LOADING_PATTERN'
  83.      This error occurs when you're trying to load a module which has
  84.      corrupted pattern data, or is truncated.
  85.  
  86. `MMERR_LOADING_SAMPLEINFO'
  87.      This error occurs when you're trying to load a module which has
  88.      corrupted sample information, or is truncated.
  89.  
  90. `MMERR_LOADING_TRACK'
  91.      This error occurs when you're trying to load a module which has
  92.      corrupted track data, or is truncated.
  93.  
  94. `MMERR_MED_SYNTHSAMPLES'
  95.      This error occurs when you're trying to load a MED module which
  96.      has synthsounds samples, which are currently not supported.(1)
  97.  
  98. `MMERR_NOT_A_MODULE'
  99.      This error occurs when you're trying to load a module which format
  100.      is not recognized.
  101.  
  102. `MMERR_NOT_A_STREAM'
  103.      This error occurs when you're trying to load a sample with a
  104.      sample which format is not recognized.
  105.  
  106. Driver Errors
  107. -------------
  108.  
  109. Generic Driver Errors
  110. .....................
  111.  
  112. `MMERR_16BIT_ONLY'
  113.      This error occurs when the sound device doesn't support non-16 bit
  114.      linear sound output, which are the requested settings.
  115.  
  116. `MMERR_8BIT_ONLY'
  117.      This error occurs when the sound device doesn't support non-8 bit
  118.      linear sound output, which are the requested settings.
  119.  
  120. `MMERR_DETECTING_DEVICE'
  121.      This error occurs when the driver's sound device has not been
  122.      detected.
  123.  
  124. `MMERR_INITIALIZING_MIXER'
  125.      This error occurs when MikMod's internal software mixer could not
  126.      be initialized properly.
  127.  
  128. `MMERR_INVALID_DEVICE'
  129.      This error occurs when the driver number (in `md_device') is out
  130.      of range.
  131.  
  132. `MMERR_NON_BLOCK'
  133.      This error occurs when the driver is unable to set the audio
  134.      device in non blocking mode.
  135.  
  136. `MMERR_OPENING_AUDIO'
  137.      This error occurs when the driver can not open sound device.
  138.  
  139. `MMERR_STEREO_ONLY'
  140.      This error occurs when the sound device doesn't support mono sound
  141.      output, which is the requested setting.
  142.  
  143. `MMERR_ULAW'
  144.      This error occurs when the sound device only supports uLaw output
  145.      (which implies mono, 8 bit, and 8000 Hz sampling rate), which
  146.      isn't the requested setting.
  147.  
  148. AudioFile Driver Specific Error
  149. ...............................
  150.  
  151. `MMERR_AF_AUDIO_PORT'
  152.      This error occurs when the AudioFile driver can not find a
  153.      suitable AudioFile port.
  154.  
  155. AIX Driver Specific Errors
  156. ..........................
  157.  
  158. `MMERR_AIX_CONFIG_CONTROL'
  159.      This error occurs when the "Control" step of the device
  160.      configuration has failed.
  161.  
  162. `MMERR_AIX_CONFIG_INIT'
  163.      This error occurs when the "Init" step of the device configuration
  164.      has failed.
  165.  
  166. `MMERR_AIX_CONFIG_START'
  167.      This error occurs when the "Start" step of the device
  168.      configuration has failed.
  169.  
  170. Ultra Driver Specific Errors
  171. ............................
  172.  
  173. `MMERR_GUS_RESET'
  174.      This error occurs when the sound device couldn't be reset.
  175.  
  176. `MMERR_GUS_SETTINGS'
  177.      This error occurs because the sound device only works in 16 bit
  178.      linear stereo sound at 44100 Hz, which is not the requested
  179.      settings.
  180.  
  181. `MMERR_GUS_TIMER'
  182.      This error occurs when the ultra driver could not setup the
  183.      playback timer.
  184.  
  185. HP-UX Driver Specific Errors
  186. ............................
  187.  
  188. `MMERR_HP_AUDIO_DESC'
  189.      This error occurs when the HP driver can not get the audio
  190.      hardware description.
  191.  
  192. `MMERR_HP_AUDIO_OUTPUT'
  193.      This error occurs when the HP driver can not select the audio
  194.      output.
  195.  
  196. `MMERR_HP_BUFFERSIZE'
  197.      This error occurs when the HP driver can not set the transmission
  198.      buffer size.
  199.  
  200. `MMERR_HP_CHANNELS'
  201.      This error occurs when the HP driver can not set the requested
  202.      number of channels.
  203.  
  204. `MMERR_HP_SETSAMPLESIZE'
  205.      This error occurs when the HP driver can not set the requested
  206.      sample size.
  207.  
  208. `MMERR_HP_SETSPEED'
  209.      This error occurs when the HP driver can not set the requested
  210.      sample rate.
  211.  
  212. Open Sound System Driver Specific Errors
  213. ........................................
  214.  
  215. `MMERR_OSS_SETFRAGMENT'
  216.      This error occurs when the OSS driver can not set audio fragment
  217.      size.
  218.  
  219. `MMERR_OSS_SETSAMPLESIZE'
  220.      This error occurs when the OSS driver can not set the requested
  221.      sample size.
  222.  
  223. `MMERR_OSS_SETSPEED'
  224.      This error occurs when the OSS driver can not set the requested
  225.      sample rate.
  226.  
  227. `MMERR_OSS_SETSTEREO'
  228.      This error occurs when the OSS driver can not set the requested
  229.      number of channels.
  230.  
  231. SGI Driver Specific Errors
  232. ..........................
  233.  
  234. `MMERR_SGI_MONO'
  235.      This error occurs when the hardware only supports stereo sound.
  236.  
  237. `MMERR_SGI_SPEED'
  238.      This error occurs when the hardware does not support the requested
  239.      sample rate.
  240.  
  241. `MMERR_SGI_STEREO'
  242.      This error occurs when the hardware only supports mono sound.
  243.  
  244. `MMERR_SGI_16BIT'
  245.      This error occurs when the hardware only supports 16 bit sound.
  246.  
  247. `MMERR_SGI_8BIT'
  248.      This error occurs when the hardware only supports 8 bit sound.
  249.  
  250. Sun Driver Specific Error
  251. .........................
  252.  
  253. `MMERR_SUN_INIT'
  254.      This error occurs when the sound device initialization failed.
  255.  
  256. OS/2 Driver Specific Errors
  257. ...........................
  258.  
  259. `MMERR_OS2_MIXSETUP'
  260.      This error occurs when the DART driver can not set the mixing
  261.      parameters.
  262.  
  263. `MMERR_OS2_SEMAPHORE'
  264.      This error occurs when the MMPM/2 driver can not create the
  265.      semaphores needed for playback.
  266.  
  267. `MMERR_OS2_THREAD'
  268.      This error occurs when the MMPM/2 driver can not create the thread
  269.      needed for playback.
  270.  
  271. `MMERR_OS2_TIMER'
  272.      This error occurs when the MMPM/2 driver can not create the timer
  273.      needed for playback.
  274.  
  275. DirectX Driver Specific Errors
  276. ..............................
  277.  
  278. `MMERR_DS_BUFFER'
  279.      This error occurs when the DirectX driver can not allocate the
  280.      playback buffers.
  281.  
  282. `MMERR_DS_EVENT'
  283.      This error occurs when the DirectX driver can not register the
  284.      playback event.
  285.  
  286. `MMERR_DS_FORMAT'
  287.      This error occurs when the DirectX driver can not set the playback
  288.      format.
  289.  
  290. `MMERR_DS_NOTIFY'
  291.      This error occurs when the DirectX driver can not register the
  292.      playback callback.
  293.  
  294. `MMERR_DS_PRIORITY'
  295.      This error occurs when the DirectX driver can not set the playback
  296.      priority.
  297.  
  298. `MMERR_DS_THREAD'
  299.      This error occurs when the DirectX driver can not create the
  300.      playback thread.
  301.  
  302. `MMERR_DS_UPDATE'
  303.      This error occurs when the DirectX driver can not initialize the
  304.      playback thread.
  305.  
  306. Windows Multimedia API Driver Specific Errors
  307. .............................................
  308.  
  309. `MMERR_WINMM_ALLOCATED'
  310.      This error occurs when the playback resource is already allocated
  311.      by another application.
  312.  
  313. `MMERR_WINMM_DEVICEID'
  314.      This error occurs when the Multimedia API Driver is given an
  315.      invalid audio device identificator.
  316.  
  317. `MMERR_WINMM_FORMAT'
  318.      This error occurs when the playback output format is not supported
  319.      by the audio device.
  320.  
  321. `MMERR_WINMM_HANDLE'
  322.      This error occurs when the Multimedia API Driver is given an
  323.      invalid handle.
  324.  
  325. `MMERR_WINMM_UNKNOWN'
  326.      This error should not occur ! If you get this error, please
  327.      contact the libmikmod development mailing list.
  328.  
  329. MacOS Driver Specific Errors
  330. ............................
  331.  
  332. `MMERR_MAC_SPEED'
  333.      This error occurs when the playback speed is not supported by the
  334.      audio device.
  335.  
  336. `MMERR_MAC_START'
  337.      This error occurs when the MacOS driver can not start playback.
  338.  
  339.    ---------- Footnotes ----------
  340.  
  341.    (1) You can force libmikmod to load the module (without the
  342. synthsounds, of course) by setting the `curious' parameter to `1' when
  343. invoking `Player_Loadxx'.
  344.  
  345. 
  346. File: mikmod.info,  Node: Function Reference,  Next: Library Core Functions,  Prev: Error Reference,  Up: Library Reference
  347.  
  348. Function Reference
  349. ==================
  350.  
  351. * Menu:
  352.  
  353. * Library Core Functions::      MikMod_xx functions.
  354. * Module Player Functions::     Player_xx functions.
  355. * Sample Functions::            Sample_xx functions.
  356. * Voice Functions::             Voice_xx functions.
  357.  
  358. 
  359. File: mikmod.info,  Node: Library Core Functions,  Next: Module Player Functions,  Prev: Function Reference,  Up: Function Reference
  360.  
  361. Library Core Functions
  362. ----------------------
  363.  
  364. MikMod_Active
  365. .............
  366.  
  367.    `BOOL MikMod_Active(void)'
  368. Description
  369.      This function returns whether sound output is enabled or not.
  370.  
  371. Result
  372. 0
  373.      Sound output is disabled.
  374.  
  375. 1
  376.      Sound output is enabled.
  377.  
  378. Notes
  379.      Calls to `MikMod_Update' will be ignored when sound output is
  380.      disabled.
  381.  
  382. See also
  383.      `MikMod_DisableOutput', `MikMod_EnableOutput'.
  384.  
  385. MikMod_DisableOutput
  386. ....................
  387.  
  388.    `void MikMod_DisableOutput(void)'
  389. Description
  390.      This function stops the sound mixing.
  391.  
  392. Notes
  393.      Calls to `MikMod_Update' will be ignored when sound output is
  394.      disabled.
  395.  
  396. See also
  397.      `MikMod_Active', `MikMod_EnableOutput'.
  398.  
  399. MikMod_EnableOutput
  400. ...................
  401.  
  402.    `BOOL MikMod_EnableOutput(void)'
  403. Description
  404.      This function starts the sound mixing.
  405.  
  406. Result
  407. 0
  408.      Sound mixing is ready.
  409.  
  410. nonzero
  411.      An error occurred during the operation.
  412.  
  413. Notes
  414.      Calls to `MikMod_Update' will be ignored when sound output is
  415.      disabled.
  416.  
  417. See also
  418.      `MikMod_Active', `MikMod_DisableOutput'.
  419.  
  420. MikMod_Exit
  421. ...........
  422.  
  423.    `void MikMod_Exit(void)'
  424. Description
  425.      This function deinitializes the sound hardware and frees all the
  426.      memory and resources used by MikMod.
  427.  
  428. See also
  429.      `MikMod_Init', `MikMod_Reset'.
  430.  
  431. MikMod_GetVersion
  432. .................
  433.  
  434.    `long MikMod_GetVersion(void)'
  435. Description
  436.      This function returns the version number of the library.
  437.  
  438. Result
  439.      The version number, encoded as follows: `(maj<<16)|(min<<8)|(rev)',
  440.      where `maj' is the major version number, `min' is the minor version
  441.      number, and `rev' is the revision number.
  442.  
  443. MikMod_InfoDriver
  444. .................
  445.  
  446.    `CHAR* MikMod_InfoDriver(void)'
  447. Description
  448.      This function returns a formatted list of the registered drivers
  449.      in a buffer.
  450.  
  451. Result
  452.      A pointer to a text buffer, or `NULL' if no drivers are registered.
  453.  
  454. Notes
  455.      The buffer is created with `malloc'; the caller must free it when
  456.      it is no longer necessary.
  457.  
  458. See also
  459.      `MikMod_RegisterDriver', `MikMod_RegisterAllDrivers'.
  460.  
  461. MikMod_InfoLoader
  462. .................
  463.  
  464.    `CHAR* MikMod_InfoLoader(void)'
  465. Description
  466.      This function returns a formatted list of the registered module
  467.      loaders in a buffer.
  468.  
  469. Result
  470.      A pointer to a text buffer, or `NULL' if no loaders are registered.
  471.  
  472. Notes
  473.      The buffer is created with `malloc'; the caller must free it when
  474.      it is no longer necessary.
  475.  
  476. See also
  477.      `MikMod_RegisterLoader', `MikMod_RegisterAllLoaders'.
  478.  
  479. MikMod_Init
  480. ...........
  481.  
  482.    `BOOL MikMod_Init(CHAR *parameters)'
  483. Description
  484.      This function performs the library initialization, including the
  485.      sound driver choice and configuration, and all the necessary
  486.      memory allocations.
  487.  
  488. Parameters
  489. parameters
  490.      Optional parameters given to the sound driver. These parameters
  491.      are ignored if the value of `md_device' is zero (autodetection).
  492.  
  493. Result
  494. 0
  495.      Initialization was successful.
  496.  
  497. nonzero
  498.      An error occurred during initialization.
  499.  
  500. Notes
  501.      When the initialization fails, the library uses the nosound sound
  502.      driver to let other the other MikMod functions work without
  503.      crashing the application.
  504.  
  505. See also
  506.      `MikMod_Exit', `MikMod_InitThreads', `MikMod_Reset'.
  507.  
  508. MikMod_InitThreads
  509. ..................
  510.  
  511.    `BOOL MikMod_InitThreads(void)'
  512. Description
  513.      This function returns whether libmikmod is thread-safe.
  514.  
  515. Result
  516. 0
  517.      The library is not thread-safe.
  518.  
  519. 1
  520.      The library is thread-safe.
  521.  
  522. Notes
  523.      This function should be called before any call to `MikMod_Lock' or
  524.      `MikMod_Unlock' is made.
  525.  
  526. See also
  527.      `MikMod_Lock', `MikMod_Unlock'.
  528.  
  529. MikMod_Lock
  530. ...........
  531.  
  532.    `void MikMod_Lock(void)'
  533. Description
  534.      This function obtains exclusive access to libmikmod's variables.
  535.  
  536. Notes
  537.      This function locks an internal mutex. If the mutex is already
  538.      locked, it will block the calling thread until the mutex is
  539.      unlocked.
  540.      Every `MikMod_Unlock' call should be associated to a `MikMod_Lock'
  541.      call. To be sure this is the case, we advise you to define and use
  542.      the following macros:
  543.      `#define MIKMOD_LOCK MikMod_Lock();{'
  544.      `#define MIKMOD_UNLOCK }MikMod_Unlock();'
  545.      The function `MikMod_InitThreads' must have been invoked before
  546.      any call to `MikMod_Lock' in made.
  547. See also
  548.      `MikMod_InitThreads', `MikMod_Unlock'.
  549.  
  550. MikMod_RegisterAllDrivers
  551. .........................
  552.  
  553.    `void MikMod_RegisterAllDrivers(void)'
  554. Description
  555.      This function registers all the available drivers.
  556.  
  557. See also
  558.      `MikMod_InfoDriver', `MikMod_RegisterDriver'.
  559.  
  560. MikMod_RegisterAllLoaders
  561. .........................
  562.  
  563.    `void MikMod_RegisterAllLoaders(void)'
  564. Description
  565.      This function registers all the available module loaders.
  566.  
  567. See also
  568.      `MikMod_InfoLoader', `MikMod_RegisterLoader'.
  569.  
  570. MikMod_RegisterDriver
  571. .....................
  572.  
  573.    `void MikMod_RegisterDriver(struct MDRIVER* newdriver)'
  574. Description
  575.      This function adds the specified driver to the internal list of
  576.      usable drivers.
  577.  
  578. Parameters
  579. newdriver
  580.      A pointer to the `MDRIVER' structure identifying the driver.
  581.  
  582. Notes
  583.      It is safe to register the same driver several times, although it
  584.      will not be duplicated in the list.
  585.      You should register all the drivers you need before calling
  586.      `MikMod_Init'.  If you want to register all the available drivers,
  587.      use `MikMod_RegisterAllDrivers' instead.
  588.  
  589. See also
  590.      `MikMod_InfoDriver', `MikMod_RegisterAllDrivers'.
  591.  
  592. MikMod_RegisterErrorHandler
  593. ...........................
  594.  
  595.    `MikMod_handler_t MikMod_RegisterErrorHandler(MikMod_handler_t
  596. newhandler)'
  597. Description
  598.      This function selects the function which should be called in case
  599.      of error.
  600.  
  601. Parameters
  602. newhandler
  603.      The new error callback function.
  604.  
  605. Result
  606.      The previous error callback function, or `NULL' if there was none.
  607.  
  608. Notes
  609.      `MikMod_handler_t' is defined as `void(*function)(void)', this
  610.      means your error function has the following prototype: `void
  611.      MyErrorHandler(void)'
  612.      The error callback function is called when errors are detected,
  613.      but not always immediately (the library has to resume to a stable
  614.      state before calling your callback).
  615.  
  616. MikMod_RegisterLoader
  617. .....................
  618.  
  619.    `void MikMod_RegisterLoader(struct MLOADER* newloader)'
  620. Description
  621.      This function adds the specified module loader to the internal
  622.      list of usable module loaders.
  623.  
  624. Parameters
  625. newloader
  626.      A pointer to the `MLOADER' structure identifying the loader.
  627.  
  628. Notes
  629.      It is safe to register the same loader several times, although it
  630.      will not be duplicated in the list.
  631.      You should register all the loaders you need before calling
  632.      `Player_Load' or `Player_LoadFP'. If you want to register all the
  633.      available module loaders, use `MikMod_RegisterAllLoaders' instead.
  634.      The 15 instrument module loader (`load_m15') should always be
  635.      registered last.
  636.  
  637. See also
  638.      `MikMod_InfoLoader', `MikMod_RegisterAllLoaders'.
  639.  
  640. MikMod_RegisterPlayer
  641. .....................
  642.  
  643.    `MikMod_player_t MikMod_RegisterPlayer(MikMod_player_t newplayer)'
  644. Description
  645.      This function selects the function which should be used to process
  646.      module playback.
  647.  
  648. Parameters
  649. newplayer
  650.      The new playback function
  651.  
  652. Result
  653.      The previous playback function.
  654.  
  655. Notes
  656.      `MikMod_player_t' is defined as `void(*function)(void)', this means
  657.      your player function has the following prototype: `void
  658.      MyPlayer(void)'
  659.      The player function is called every module tick to process module
  660.      playback.  The rate at which the player function is called is
  661.      controlled by the sound driver, and is computed by the following
  662.      equation:
  663.      (bpm*50)/125 calls per second, which means every 125000/(bpm*50)
  664.      milliseconds. The `bpm' value is the tempo of the module and can
  665.      change from its initial value when requested by the module.
  666.      When changing the playback function, you should make sure that you
  667.      chain to the default MikMod playback function, otherwise you won't
  668.      get module sound anymore....
  669.  
  670. Example
  671.               MikMod_player_t oldroutine;
  672.           
  673.               void MyPlayer(void)
  674.               {
  675.                   oldroutine();
  676.                   /* your stuff here */
  677.                   ...
  678.               }
  679.           
  680.               main()
  681.               {
  682.                   ...
  683.                   /* Register our player */
  684.                   oldroutine = MikMod_RegisterPlayer(MyPlayer);
  685.                   ...
  686.               }
  687.  
  688. MikMod_Reset
  689. ............
  690.  
  691.    `BOOL MikMod_Reset(CHAR *parameters)'
  692. Description
  693.      This function resets MikMod and reinitialize the sound hardware.
  694.  
  695. Parameters
  696. parameters
  697.      Optional parameters given to the sound driver. If you set the
  698.      value of `md_device' to zero (autodetect), these parameters are
  699.      ignored.
  700.  
  701. Result
  702. 0
  703.      Reinitialization was successful.
  704.  
  705. nonzero
  706.      An error occurred during reinitialization.
  707.  
  708. Notes
  709.      Use this function when you have changed the global configuration
  710.      variables: `md_device' and `md_mixfreq', or one of the `md_mode'
  711.      flags which require sound reinitialization. Sound playback will
  712.      continue as soon as the driver is ready.
  713.  
  714. See also
  715.      `MikMod_Exit', `MikMod_Init'.
  716.  
  717. MikMod_SetNumVoices
  718. ...................
  719.  
  720.    `BOOL MikMod_SetNumVoices(int musicvoices, int samplevoices)'
  721. Description
  722.      This function sets the number of mixed voices which can be used
  723.      for music and sound effects playback.
  724.  
  725. Parameters
  726. musicvoices
  727.      The number of voices to reserve for music playback.
  728.  
  729. samplevoices
  730.      The number of voices to reserve for sound effects.
  731.  
  732. Result
  733. 0
  734.      Initialization was successful.
  735.  
  736. nonzero
  737.      An error occurred during initialization.
  738.  
  739. Notes
  740.      A value of `-1' for any of the parameters will retain the current
  741.      number of reserved voices.
  742.      The maximum number of voices vary from driver to driver (hardware
  743.      drivers often have a limit of 32 to 64 voices, whereas the
  744.      software drivers handle 255 voices). If your settings exceed the
  745.      driver's limit, they will be truncated.
  746.  
  747. See also
  748.      `MikMod_Init', `MikMod_Reset'.
  749.  
  750. MikMod_Unlock
  751. .............
  752.  
  753.    `void MikMod_Unlock(void)'
  754. Description
  755.      This function relinquishes exclusive access to libmikmod's
  756.      variables.
  757.  
  758. Notes
  759.      This function unlocks an internal mutex, so that other threads
  760.      waiting for the lock can be resumed.
  761.      Every `MikMod_Unlock' call should be associated to a `MikMod_Lock'
  762.      call. To be sure this is the case, we advise you to define and use
  763.      the following macros:
  764.      `#define MIKMOD_LOCK MikMod_Lock();{'
  765.      `#define MIKMOD_UNLOCK }MikMod_Unlock();'
  766.      The function `MikMod_InitThreads' must have been invoked before
  767.      any call to `MikMod_Unlock' in made.
  768. See also
  769.      `MikMod_InitThreads', `MikMod_Lock'.
  770.  
  771. MikMod_Update
  772. .............
  773.  
  774.    `void MikMod_Update(void)'
  775. Description
  776.      This routine should be called on a regular basis to update the
  777.      sound.
  778.  
  779. Notes
  780.      The sound output buffer is filled each time this function is
  781.      called; if you use a large buffer, you don't need to call this
  782.      routine as frequently as with a smaller buffer, but you get a
  783.      bigger shift between the sound being played and the reported state
  784.      of the player, since the player is always a buffer ahead of the
  785.      playback.
  786.      If you play low quality sound (for example, mono 8 bit 11kHz
  787.      sound), you only need to call this routine a few times per second.
  788.      However, for high quality sound (stereo 16 bit 44kHz), this rate
  789.      increases to a few hundred times per second, but never more, due
  790.      to the minimal buffer size constraint imposed to the sound drivers.
  791.      If you plan on modifying voice information with the `Voice_xx'
  792.      functions, you should do this before calling `MikMod_Update'.
  793.  
  794. MikMod_strerror
  795. ...............
  796.  
  797.    `char* MikMod_strerror(int errno)'
  798. Description
  799.      This function associates a descriptive message to an error code.
  800.  
  801. Parameters
  802. errno
  803.      The MikMod error code.
  804.  
  805. Result
  806.      A pointer to a string describing the error.
  807.  
  808. 
  809. File: mikmod.info,  Node: Module Player Functions,  Next: Sample Functions,  Prev: Library Core Functions,  Up: Function Reference
  810.  
  811. Module Player Functions
  812. -----------------------
  813.  
  814. Player_Active
  815. .............
  816.  
  817.    `BOOL Player_Active(void)'
  818. Description
  819.      This function returns whether the module player is active or not.
  820.  
  821. Result
  822. 0
  823.      No module is playing.
  824.  
  825. nonzero
  826.      A module is currently playing.
  827.  
  828. Notes
  829.      This function will still report that the player is active if the
  830.      playing module is paused.
  831.  
  832. See also
  833.      `Player_Paused', `Player_TogglePause', `Player_Start',
  834.      `Player_Stop'
  835.  
  836. Player_Free
  837. ...........
  838.  
  839.    `void Player_Free(MODULE* module)'
  840. Description
  841.      This function stops the module if it is playing and unloads it
  842.      from memory.
  843.  
  844. Parameters
  845. module
  846.      The module to free.
  847.  
  848. See also
  849.      `Player_Load', `Player_LoadFP'.
  850.  
  851. Player_GetChannelVoice
  852. ......................
  853.  
  854.    `int Player_GetChannelVoice(UBYTE channel)'
  855. Description
  856.      This function determines the voice corresponding to the specified
  857.      module channel.
  858.  
  859. Parameters
  860. channel
  861.      The module channel to use.
  862.  
  863. Result
  864.      The number of the voice corresponding to the module channel.
  865.  
  866. Notes
  867.      If the module channel has NNAs, the number will correspond to the
  868.      main channel voice.
  869.  
  870. See also
  871.      `Voice_SetPanning', `Voice_SetVolume', `Player_Mute',
  872.      `Player_ToggleMute', `Player_Unmute'.
  873.  
  874. Player_GetModule
  875. ................
  876.  
  877.    `MODULE* Player_GetModule(void)'
  878. Description
  879.      This function returns the module currently being played.
  880.  
  881. Result
  882.      A pointer to the `MODULE' being played, or `NULL' if no module is
  883.      playing.
  884.  
  885. See also
  886.      `Player_Stop', `Player_Start'.
  887.  
  888. Player_Load
  889. ...........
  890.  
  891.    `MODULE* Player_Load(CHAR* filename, int maxchan, BOOL curious)'
  892. Description
  893.      This function loads a music module.
  894.  
  895. Parameters
  896. filename
  897.      The name of the module file.
  898.  
  899. maxchan
  900.      The maximum number of channels the song is allowed to request from
  901.      the mixer.
  902.  
  903. curious
  904.      The curiosity level to use.
  905.  
  906. Result
  907.      A pointer to a `MODULE' structure, or `NULL' if an error occurs.
  908.  
  909. Notes
  910.      If the curiosity level is set to zero, the module will be loaded
  911.      normally.  However, if it is nonzero, the following things occur:
  912.         * pattern positions occurring after the "end of song" marker in
  913.           S3M and IT modules are loaded, and the end of song is set to
  914.           the last position.
  915.  
  916.         * hidden extra patterns are searched in MOD modules, and if
  917.           found, played after the last "official" pattern.
  918.  
  919.         * MED modules with synthsounds are loaded without causing the
  920.           `MMERR_MED_SYNTHSAMPLES', and synthsounds are mapped to an
  921.           empty sample.
  922.  
  923. See also
  924.      `Player_Free', `Player_LoadFP', `Player_LoadTitle',
  925.      `Player_LoadTitleFP', `Player_Start'.
  926.  
  927. Player_LoadFP
  928. .............
  929.  
  930.    `MODULE* Player_LoadFP(FILE* file, int maxchan, BOOL curious)'
  931. Description
  932.      This function loads a music module.
  933.  
  934. Parameters
  935. file
  936.      An open file, at the position where the module starts.
  937.  
  938. maxchan
  939.      The maximum number of channels the song is allowed to request from
  940.      the mixer.
  941.  
  942. curious
  943.      The curiosity level to use.
  944.  
  945. Result
  946.      A pointer to a `MODULE' structure, or `NULL' if an error occurs.
  947.  
  948. Notes
  949.      The file is left open, at the same position as before the function
  950.      call.
  951.      If the curiosity level is set to zero, the module will be loaded
  952.      normally.  However, if it is nonzero, the following things occur:
  953.         * pattern positions occurring after the "end of song" marker in
  954.           S3M and IT modules are loaded, and the end of song is set to
  955.           the last position.
  956.  
  957.         * hidden extra patterns are searched in MOD modules, and if
  958.           found, played after the last "official" pattern.
  959.  
  960.         * MED modules with synthsounds are loaded without causing the
  961.           `MMERR_MED_SYNTHSAMPLES', and synthsounds are mapped to an
  962.           empty sample.
  963.  
  964. See also
  965.      `Player_Free', `Player_Load', `Player_LoadTitle',
  966.      `Player_LoadTitleFP', `Player_Start'.
  967.  
  968. Player_LoadTitle
  969. ................
  970.  
  971.    `MODULE* Player_LoadTitle(CHAR* filename)'
  972. Description
  973.      This function retrieves the title of a module file.
  974.  
  975. Parameters
  976. filename
  977.      The name of the module file.
  978.  
  979. Result
  980.      A pointer to the song title, or `NULL' if either the module has no
  981.      title or an error has occurred.
  982.  
  983. Notes
  984.      The title buffer is created with `malloc'; the caller must free it
  985.      when it is no longer necessary.
  986.  
  987. See also
  988.      `Player_Load', `Player_LoadFP', `Player_LoadTitleFP'.
  989.  
  990. Player_LoadTitleFP
  991. ..................
  992.  
  993.    `MODULE* Player_LoadTitleFP(FILE* file)'
  994. Description
  995.      This function retrieves the title of a module file.
  996.  
  997. Parameters
  998. file
  999.      An open file, at the position where the module starts.
  1000.  
  1001. Result
  1002.      A pointer to the song title, or `NULL' if either the module has no
  1003.      title or an error has occurred.
  1004.  
  1005. Notes
  1006.      The title buffer is created with `malloc'; the caller must free it
  1007.      when it is no longer necessary.
  1008.  
  1009. See also
  1010.      `Player_Load', `Player_LoadFP', `Player_LoadTitle'.
  1011.  
  1012. Player_Mute
  1013. ...........
  1014.  
  1015.    `void Player_Mute(SLONG operation, ...)'
  1016. Description
  1017.      This function mutes a single module channel, or a range of module
  1018.      channels.
  1019.  
  1020. Parameters
  1021. operation
  1022.      Either the number of a module channel to mute (starting from
  1023.      zero), or an operation code. In the latter case, two extra
  1024.      parameters are needed to determine the range of channels.
  1025.  
  1026. Notes
  1027.      If the operation is `MUTE_INCLUSIVE', the two channel numbers
  1028.      delimit the range and are part of the range ; otherwise, if the
  1029.      operation is `MUTE_EXCLUSIVE', they are outside of the range.
  1030.  
  1031. Example
  1032.               /* mute channel 10 */
  1033.               Player_Mute(10);
  1034.               /* mute channels 2 to 5 */
  1035.               Player_Mute(MUTE_INCLUSIVE, 2, 5);
  1036.               /* mute channels 7 to 9 */
  1037.               Player_Mute(MUTE_EXCLUSIVE, 6, 10);
  1038.  
  1039. See also
  1040.      `Player_Muted', `Player_ToggleMute', `Player_Unmute'.
  1041.  
  1042. Player_Muted
  1043. ............
  1044.  
  1045.    `BOOL Player_Muted(UBYTE channel)'
  1046. Description
  1047.      This function determines whether a module channel is muted or not.
  1048.  
  1049. Parameters
  1050. channel
  1051.      The module channel to test (starting from zero).
  1052.  
  1053. Result
  1054. 0
  1055.      The channel is not muted.
  1056.  
  1057. 1
  1058.      The channel is muted.
  1059.  
  1060. See also
  1061.      `Player_Mute', `Player_ToggleMute', `Player_Unmute'.
  1062.  
  1063. Player_NextPosition
  1064. ...................
  1065.  
  1066.    `void Player_NextPosition(void)'
  1067. Description
  1068.      This function jumps to the next position in the module.
  1069.  
  1070. Notes
  1071.      All playing samples and active song voices are cut to avoid
  1072.      hanging notes.
  1073.  
  1074. See also
  1075.      `Player_PrevPosition', `Player_SetPosition'.
  1076.  
  1077. Player_Paused
  1078. .............
  1079.  
  1080.    `BOOL Player_Paused(void)'
  1081. Description
  1082.      This function determines whether the module is paused or not.
  1083.  
  1084. Result
  1085. 0
  1086.      The module is not paused.
  1087.  
  1088. 1
  1089.      The module is paused.
  1090.  
  1091. See also
  1092.      `Player_TogglePause'.
  1093.  
  1094. Player_PrevPosition
  1095. ...................
  1096.  
  1097.    `void Player_PrevPosition(void)'
  1098. Description
  1099.      This function jumps to the previous position in the module.
  1100.  
  1101. Notes
  1102.      All playing samples and active song voices are cut to avoid
  1103.      hanging notes.
  1104.  
  1105. See also
  1106.      `Player_NextPosition', `Player_SetPosition'.
  1107.  
  1108. Player_SetPosition
  1109. ..................
  1110.  
  1111.    `void Player_SetPosition(UWORD position)'
  1112. Description
  1113.      This function jumps to the specified position in the module.
  1114.  
  1115. Parameters
  1116. position
  1117.      The pattern position to jump to.
  1118.  
  1119. Notes
  1120.      All playing samples and active song voices are cut to avoid
  1121.      hanging notes.
  1122.  
  1123. See also
  1124.      `Player_NextPosition', `Player_PrevPosition'.
  1125.  
  1126. Player_SetSpeed
  1127. ...............
  1128.  
  1129.    `void Player_SetSpeed(UWORD speed)'
  1130. Description
  1131.      This function sets the module speed.
  1132.  
  1133. Parameters
  1134. speed
  1135.      The new module speed, in the range 1-32.
  1136.  
  1137. See also
  1138.      `Player_SetTempo'.
  1139.  
  1140. Player_SetTempo
  1141. ...............
  1142.  
  1143.    `void Player_SetTempo(UWORD tempo)'
  1144. Description
  1145.      This function sets the module tempo.
  1146.  
  1147. Parameters
  1148. tempo
  1149.      The new module tempo, in the range 32-255.
  1150.  
  1151. See also
  1152.      `Player_SetSpeed'.
  1153.  
  1154. Player_SetVolume
  1155. ................
  1156.  
  1157.    `void Player_SetVolume(SWORD volume)'
  1158. Description
  1159.      This function sets the module volume.
  1160.  
  1161. Parameters
  1162. volume
  1163.      The new overall module playback volume, in the range 0-128.
  1164.  
  1165. Player_Start
  1166. ............
  1167.  
  1168.    `void Player_Start(MODULE* module)'
  1169. Description
  1170.      This function starts the specified module playback.
  1171.  
  1172. Parameters
  1173. module
  1174.      The module to play.
  1175.  
  1176. Notes
  1177.      If another module is playing, it will be stopped and the new
  1178.      module will play.
  1179.  
  1180. See also
  1181.      `Player_Stop'.
  1182.  
  1183. Player_Stop
  1184. ...........
  1185.  
  1186.    `void Player_Stop(void)'
  1187. Description
  1188.      This function stops the currently playing module.
  1189.  
  1190. See also
  1191.      `Player_Start'.
  1192.  
  1193. Player_ToggleMute
  1194. .................
  1195.  
  1196.    `void Player_ToggleMute(SLONG operation, ...)'
  1197. Description
  1198.      This function changes the muted status of a single module channel,
  1199.      or a range of module channels.
  1200.  
  1201. Parameters
  1202. operation
  1203.      Either the number of a module channel to work on (starting from
  1204.      zero), or an operation code. In the latter case, two extra
  1205.      parameters are needed to determine the range of channels.
  1206.  
  1207. Notes
  1208.      If the operation is `MUTE_INCLUSIVE', the two channel numbers
  1209.      delimit the range and are part of the range ; otherwise, if the
  1210.      operation is `MUTE_EXCLUSIVE', they are outside of the range.
  1211.  
  1212. Example
  1213.               /* toggle mute on channel 10 */
  1214.               Player_ToggleMute(10);
  1215.               /* toggle mute on channels 2 to 5 */
  1216.               Player_ToggleMute(MUTE_INCLUSIVE, 2, 5);
  1217.               /* toggle mute on channels 7 to 9 */
  1218.               Player_ToggleMute(MUTE_EXCLUSIVE, 6, 10);
  1219.  
  1220. See also
  1221.      `Player_Mute', `Player_Muted', `Player_Unmute'.
  1222.  
  1223. Player_TogglePause
  1224. ..................
  1225.  
  1226.    `void Player_TogglePause(void)'
  1227. Description
  1228.      This function toggles the playing/paused status of the module.
  1229.  
  1230. Notes
  1231.      Calls to `Player_xx' functions still have effect when the module
  1232.      is paused.
  1233.  
  1234. See also
  1235.      `Player_Paused', `Player_Start', `Player_Stop'.
  1236.  
  1237. Player_Unmute
  1238. .............
  1239.  
  1240.    `void Player_Unmute(SLONG operation, ...)'
  1241. Description
  1242.      This function unmutes a single module channel, or a range of
  1243.      module channels.
  1244.  
  1245. Parameters
  1246. operation
  1247.      Either the number of a module channel to unmute (starting from
  1248.      zero), or an operation code. In the latter case, two extra
  1249.      parameters are needed to determine the range of channels.
  1250.  
  1251. Notes
  1252.      If the operation is `MUTE_INCLUSIVE', the two channel numbers
  1253.      delimit the range and are part of the range ; otherwise, if the
  1254.      operation is `MUTE_EXCLUSIVE', they are outside of the range.
  1255.  
  1256. Example
  1257.               /* unmute channel 10 */
  1258.               Player_Unmute(10);
  1259.               /* unmute channels 2 to 5 */
  1260.               Player_Unmute(MUTE_INCLUSIVE, 2, 5);
  1261.               /* unmute channels 7 to 9 */
  1262.               Player_Unmute(MUTE_EXCLUSIVE, 6, 10);
  1263.  
  1264. See also
  1265.      `Player_Mute', `Player_Muted', `Player_ToggleMute'.
  1266.  
  1267. 
  1268. File: mikmod.info,  Node: Sample Functions,  Next: Voice Functions,  Prev: Module Player Functions,  Up: Function Reference
  1269.  
  1270. Sample Functions
  1271. ----------------
  1272.  
  1273. Sample_Free
  1274. ...........
  1275.  
  1276.    `void Sample_Free(SAMPLE* sample)'
  1277. Description
  1278.      This function unloads a sample from memory.
  1279.  
  1280. Parameters
  1281. sample
  1282.      The sample to free.
  1283.  
  1284. See also
  1285.      `Sample_Load', `Sample_LoadFP'.
  1286.  
  1287. Sample_Load
  1288. ...........
  1289.  
  1290.    `SAMPLE* Sample_Load(CHAR* filename)'
  1291. Description
  1292.      This function loads a sample.
  1293.  
  1294. Parameters
  1295. filename
  1296.      The sample filename.
  1297.  
  1298. Result
  1299.      A pointer to a `SAMPLE' structure, or `NULL' if an error has
  1300.      occurred.
  1301.  
  1302. See also
  1303.      `Sample_Free', `Sample_LoadFP'.
  1304.  
  1305. Sample_LoadFP
  1306. .............
  1307.  
  1308.    `SAMPLE* Sample_LoadFP(FILE* file)'
  1309. Description
  1310.      This function loads a sample.
  1311.  
  1312. Parameters
  1313. file
  1314.      An open file, at the position where the sample starts.
  1315.  
  1316. Result
  1317.      A pointer to a `SAMPLE' structure, or `NULL' if an error has
  1318.      occurred.
  1319.  
  1320. Notes
  1321.      The file is left open, at the same position as before the function
  1322.      call.
  1323.  
  1324. See also
  1325.      `Sample_Free', `Sample_Load'.
  1326.  
  1327. Sample_Play
  1328. ...........
  1329.  
  1330.    `SBYTE Sample_Play(SAMPLE* sample, ULONG start, UBYTE flags)'
  1331. Description
  1332.      This function plays a sample as a sound effect.
  1333.  
  1334. Parameters
  1335. sample
  1336.      The sample to play.
  1337.  
  1338. start
  1339.      The starting position (in samples).
  1340.  
  1341. flags
  1342.      Either zero, for normal sound effects, or `SFX_CRITICAL', for
  1343.      critical sound effects which must not be interrupted.
  1344.  
  1345. Result
  1346.      The voice number corresponding to the voice which will play the
  1347.      sample.
  1348.  
  1349. Notes
  1350.      Each new sound effect is played on a new voice. When all voices
  1351.      are taken, the oldest sample which was not marked as critical is
  1352.      cut and its voice is used for the new sample. Critical samples are
  1353.      not cut unless all the voices are taken with critical samples and
  1354.      you attempt to play yet another critical sample. Use `Voice_Stop'
  1355.      to force the end of a critical sample.
  1356.  
  1357. See also
  1358.      `MikMod_SetNumVoices', `Voice_Play', `Voice_SetFrequency',
  1359.      `Voice_SetPanning', `Voice_SetVolume', `Voice_Stop'.
  1360.  
  1361. 
  1362. File: mikmod.info,  Node: Voice Functions,  Next: Loader Reference,  Prev: Sample Functions,  Up: Function Reference
  1363.  
  1364. Voice Functions
  1365. ---------------
  1366.  
  1367. Voice_GetFrequency
  1368. ..................
  1369.  
  1370.    `ULONG Voice_GetFrequency(SBYTE voice)'
  1371. Description
  1372.      This function returns the frequency of the sample currently
  1373.      playing on the specified voice.
  1374.  
  1375. Parameters
  1376. voice
  1377.      The number of the voice to get frequency.
  1378.  
  1379. Result
  1380.      The current frequency of the sample playing on the specified
  1381.      voice, or zero if no sample is currently playing on the voice.
  1382.  
  1383. See also
  1384.      `Voice_SetFrequency'.
  1385.  
  1386. Voice_GetPanning
  1387. ................
  1388.  
  1389.    `ULONG Voice_GetPanning(SBYTE voice)'
  1390. Description
  1391.      This function returns the panning position of the sample currently
  1392.      playing on the specified voice.
  1393.  
  1394. Parameters
  1395. voice
  1396.      The number of the voice to get panning position.
  1397.  
  1398. Result
  1399.      The current panning position of the sample playing on the
  1400.      specified voice, or `PAN_CENTER' if no sample is currently playing
  1401.      on the voice.
  1402.  
  1403. See also
  1404.      `Voice_SetPanning'.
  1405.  
  1406. Voice_GetPosition
  1407. .................
  1408.  
  1409.    `SLONG Voice_GetPosition(SBYTE voice)'
  1410. Description
  1411.      This function returns the sample position (in samples) of the
  1412.      sample currently playing on the specified voice.
  1413.  
  1414. Parameters
  1415. voice
  1416.      The number of the voice to get sample position (starting from
  1417.      zero).
  1418.  
  1419. Result
  1420.      The current play location of the sample playing on the specified
  1421.      voice, or zero if the position can not be determined or if no
  1422.      sample is currently playing on the voice.
  1423.  
  1424. Notes
  1425.      This function may not work with some drivers (especially for
  1426.      hardware mixed voices). In this case, it returns always `-1'.
  1427.  
  1428. See also
  1429.      `Sample_Play', `Voice_Play'.
  1430.  
  1431. Voice_GetVolume
  1432. ...............
  1433.  
  1434.    `UWORD Voice_GetVolume(SBYTE voice)'
  1435. Description
  1436.      This function returns the volume of the sample currently playing
  1437.      on the specified voice.
  1438.  
  1439. Parameters
  1440. voice
  1441.      The number of the voice to get volume.
  1442.  
  1443. Result
  1444.      The current volume of the sample playing on the specified voice,
  1445.      or zero if no sample is currently playing on the voice.
  1446.  
  1447. See also
  1448.      `Voice_RealVolume', `Voice_SetVolume'.
  1449.  
  1450. Voice_Play
  1451. ..........
  1452.  
  1453.    `void Voice_Play(SBYTE voice, SAMPLE* sample, ULONG start)'
  1454. Description
  1455.      Start a new sample in the specified voice.
  1456.  
  1457. Parameters
  1458. voice
  1459.      The number of the voice to be processed (starting from zero).
  1460.  
  1461. sample
  1462.      The sample to play.
  1463.  
  1464. start
  1465.      The starting position (in samples).
  1466.  
  1467. Notes
  1468.      The sample will be played at the volume, panning and frequency
  1469.      settings of the voice, regardless or the sample characteristics.
  1470.      The sample played this way gets the same "critical" status as the
  1471.      sample which was previously played on this voice.
  1472.  
  1473. See also
  1474.      `Sample_Play', `Voice_SetFrequency', `Voice_SetPanning',
  1475.      `Voice_SetVolume'.
  1476.  
  1477. Voice_RealVolume
  1478. ................
  1479.  
  1480.    `ULONG Voice_RealVolume(SBYTE voice)'
  1481. Description
  1482.      This function returns the actual playing volume of the specified
  1483.      voice.
  1484.  
  1485. Parameters
  1486. voice
  1487.      The number of the voice to analyze (starting from zero).
  1488.  
  1489. Result
  1490.      The real volume of the voice when the function was called, in the
  1491.      range 0-65535, not related to the volume constraint specified with
  1492.      `Voice_SetVolume'.
  1493.  
  1494. Notes
  1495.      This function may not work with some drivers (especially for
  1496.      hardware mixed voices). In this case, it always returns zero.
  1497.      Also note that the real volume computation is not a trivial
  1498.      process and takes some CPU time.
  1499.  
  1500. See also
  1501.      `Sample_Play', `Voice_GetVolume', `Voice_Play', `Voice_SetVolume'.
  1502.  
  1503. Voice_SetFrequency
  1504. ..................
  1505.  
  1506.    `void Voice_SetFrequency(SBYTE voice, ULONG frequency)'
  1507. Description
  1508.      This function sets the frequency (pitch) of the specified voice.
  1509.  
  1510. Parameters
  1511. voice
  1512.      The number of the voice to be processed (starting from zero).
  1513.  
  1514. frequency
  1515.      The new frequency of the voice, in hertz.
  1516.  
  1517. See also
  1518.      `Sample_Play', `Voice_GetFrequency', `Voice_Play',
  1519.      `Voice_SetPanning', `Voice_SetVolume', `Voice_Stop'.
  1520.  
  1521. Voice_SetPanning
  1522. ................
  1523.  
  1524.    `void Voice_SetPanning(SBYTE voice, ULONG panning)'
  1525. Description
  1526.      This function sets the panning position of the specified voice.
  1527.  
  1528. Parameters
  1529. voice
  1530.      The number of the voice to be processed (starting from zero).
  1531.  
  1532. panning
  1533.      The new panning position of the voice.
  1534.  
  1535. Notes
  1536.      Panning can vary between 0 (`PAN_LEFT') and 255 (`PAN_RIGHT').
  1537.      Center is 127 (`PAN_CENTER'. Surround sound can be enabled by
  1538.      specifying the special value `PAN_SURROUND'.
  1539.  
  1540. See also
  1541.      `Sample_Play', `Voice_GetPanning', `Voice_Play',
  1542.      `Voice_SetFrequency', `Voice_SetVolume', `Voice_Stop'.
  1543.  
  1544. Voice_SetVolume
  1545. ...............
  1546.  
  1547.    `void Voice_SetVolume(SBYTE voice, UWORD volume)'
  1548. Description
  1549.      This function sets the volume of the specified voice.
  1550.  
  1551. Parameters
  1552. voice
  1553.      The number of the voice to be processed (starting from zero).
  1554.  
  1555. volume
  1556.      The new volume of the voice, in the range 0-256.
  1557.  
  1558. See also
  1559.      `Sample_Play', `Voice_GetVolume', `Voice_Play',
  1560.      `Voice_SetFrequency', `Voice_SetPanning', `Voice_Stop'.
  1561.  
  1562. Voice_Stop
  1563. ..........
  1564.  
  1565.    `void Voice_Stop(SBYTE voice)'
  1566. Description
  1567.      This function stops the playing sample of the specified voice.
  1568.  
  1569. Parameters
  1570. voice
  1571.      The number of the voice to be processed (starting from zero).
  1572.  
  1573. Notes
  1574.      After the call to `Voice_Stop', the function `Voice_Stopped' will
  1575.      return nonzero (true) for the voice. If you want to silence the
  1576.      voice without stopping the playback, use `Voice_SetVolume(voice,
  1577.      0)' instead.
  1578.  
  1579. See also
  1580.      `Sample_Play', `Voice_Play', `Voice_SetFrequency',
  1581.      `Voice_SetPanning', `Voice_SetVolume'.
  1582.  
  1583. Voice_Stopped
  1584. .............
  1585.  
  1586.    `BOOL Voice_Stopped(SBYTE voice)'
  1587. Description
  1588.      This function returns whether the voice is active or not.
  1589.  
  1590. Parameters
  1591. voice
  1592.      The number of the voice to be checked (starting from zero).
  1593.  
  1594. Result
  1595. 0
  1596.      The voice is stopped or has no sample assigned.
  1597.  
  1598. nonzero
  1599.      The voice is playing a sample.
  1600.  
  1601. Notes
  1602.      This function may not work with some drivers (especially for
  1603.      hardware mixed voices). In this case, its return value is
  1604.      undefined.
  1605.  
  1606. See also
  1607.      `Voice_Stop'.
  1608.  
  1609. 
  1610. File: mikmod.info,  Node: Loader Reference,  Next: Module Loaders,  Prev: Voice Functions,  Up: Library Reference
  1611.  
  1612. Loader Reference
  1613. ================
  1614.  
  1615. * Menu:
  1616.  
  1617. * Module Loaders::
  1618. * Sample Loaders::
  1619.  
  1620. 
  1621. File: mikmod.info,  Node: Module Loaders,  Next: Sample Loaders,  Prev: Loader Reference,  Up: Loader Reference
  1622.  
  1623. Module Loaders
  1624. --------------
  1625.  
  1626.    MikMod presents a large choice of module loaders, for the most
  1627. common formats as well as for some less-known exotic formats.
  1628.  
  1629. `load_669'
  1630.      This loader recognizes "Composer 669" and "Unis 669" modules. The
  1631.      669 and "Extended 669" formats were among the first PC module
  1632.      formats. They do not have a wide range of effects, but support up
  1633.      to 32 channels.
  1634.      "Composer 669" was written by Tran of Renaissance, a.k.a. Tomasz
  1635.      Pytel and released in 1992. "Unis 669 Composer" was written by
  1636.      Jason Nunn and released in 1994.
  1637.  
  1638. `load_amf'
  1639.      This loader recognizes the "Advanced Module Format", which is the
  1640.      internal module format of the "DOS Sound and Music Interface"
  1641.      (DSMI) library. This format has the same limitations as the S3M
  1642.      format. The most famous DSMI application was DMP, the Dual Module
  1643.      Player.
  1644.      DMP and the DSMI library were written by Otto Chrons. DSMI was
  1645.      first released in 1993.
  1646.  
  1647. `load_dsm'
  1648.      This loader recognizes the internal DSIK format, which is the
  1649.      internal module format of the "Digital Sound Interface Kit" (DSIK)
  1650.      library, the ancester of the SEAL library. This format has the
  1651.      same limitations as the S3M format.
  1652.      The DSIK library was written by Carlos Hasan and released in 1994.
  1653.  
  1654. `load_far'
  1655.      This loader recognizes "Farandole" modules. These modules can be
  1656.      up to 16 channels and have Protracker comparable effects.
  1657.      The Farandole composer was written by Daniel Potter and released
  1658.      in 1994.
  1659.  
  1660. `load_gdm'
  1661.      This loader recognizes the "General DigiMusic" format, which is
  1662.      the internal format of the "Bells, Whistles and Sound Boards"
  1663.      library. This format has the same limitations as the S3M format.
  1664.      The BWSB library was written by Edward Schlunder and first
  1665.      released in 1993.
  1666.  
  1667. `load_imf'
  1668.      This loader recognizes "Imago Orpheus" modules. This format is
  1669.      roughly equivalent to the XM format, but with two effects columns
  1670.      instead of a volume column and an effect column.
  1671.      Imago Orpheus was written by Lutz Roeder and released in 1994.
  1672.  
  1673. `load_it'
  1674.      This loader recognizes "Impulse Tracker" modules, currently the
  1675.      most powerful format. These modules support up to 64 real
  1676.      channels, and up to 256 virtual channels with the "New Note
  1677.      Action" feature. Besides, it has the widest range of effects, and
  1678.      supports 16 bit samples as well as surround sound.
  1679.      "Impulse Tracker" was written by Jeffrey Lim and released in 1996.
  1680.  
  1681. `load_med'
  1682.      This loader recognizes "OctaMED" modules. These modules are
  1683.      comparable to Protracker modules, but can embed "synthsounds",
  1684.      which are midi-like instruments.
  1685.      "MED" and later "OctaMED" were written by Teijo Kinnunen. "MED" was
  1686.      released in 1989, and "OctaMED" was released in 1992.
  1687.  
  1688. `load_m15'
  1689.      This loader recognizes the old 15 instrument modules, created by
  1690.      "Ultimate Soundtracker", "Soundtracker" and the first versions of
  1691.      "Protracker".
  1692.      Since this format was one of the first module formats, developed
  1693.      in 1987, it does not have any signature field, which makes it hard
  1694.      to detect reliably, because of its similarities with later module
  1695.      formats.
  1696.  
  1697. `load_mod'
  1698.      This loader recognizes the standard 31 instrument modules, created
  1699.      by "Protracker" or Protracker-compatible programs. The original
  1700.      Protracker format was limited to 4 channels, but other trackers
  1701.      like "TakeTracker", "StarTracker" or "Oktalyzer" afforded more
  1702.      channels.
  1703.      Although it is now technically obsolete, this format is still
  1704.      widely used, due to its playback simplicity (on the adequate
  1705.      hardware, the Amiga).
  1706.  
  1707. `load_mtm'
  1708.      This loader recognizes the "MultiTracker Module Editor" modules.
  1709.      The MTM format has up to 32 channels, and protracker comparable
  1710.      effects. It was intended to replace "Composer 669".  The
  1711.      "MultiTracker Module Editor" was written by Starscream of
  1712.      Renaissance, a.k.a. Daniel Goldstein and released in late 1993.
  1713.  
  1714. `load_okt'
  1715.      This loader recognizes the "Amiga Oktalyzer" modules. The OKT
  1716.      format has up to 8 channels, and a few protracker compatible
  1717.      effects, as well as other OKT-specific effects, which are
  1718.      currently not supported by libmikmod.
  1719.  
  1720. `load_stm'
  1721.      This loader recognizes "ScreamTracker" modules. "ScreamTracker"
  1722.      was the first PC tracker, as well as the first PC module format.
  1723.      Loosely inspired by the "SoundTracker" format, it does not have as
  1724.      many effects as Protracker, although it supports 31 instruments
  1725.      and 4 channels.
  1726.      "ScreamTracker" was written by PSI of Future Crew, a.k.a. Sami
  1727.      Tammilehto.
  1728.  
  1729. `load_stx'
  1730.      This loader recognizes "STMIK 0.2" modules. "STMIK" (the Scream
  1731.      Tracker Music Interface Kit) was a module playing library
  1732.      distributed by Future Crew to play Scream Tracker module in games
  1733.      and demos. It uses an intermediate format between STM and S3M and
  1734.      comes with a tool converting STM modules to STX.
  1735.      "STMIK" was written by PSI of Future Crew, a.k.a. Sami Tammilehto.
  1736.  
  1737. `load_s3m'
  1738.      This loader recognizes "ScreamTracker 3" modules. This version was
  1739.      a huge improvement over the original "ScreamTracker". It supported
  1740.      32 channels, up to 99 instruments, and a large choice of effects.
  1741.      "ScreamTracker 3" was written by PSI of Future Crew, a.k.a. Sami
  1742.      Tammilehto, and released in 1994.
  1743.  
  1744. `load_ult'
  1745.      This loader recognizes "UltraTracker" modules. They are mostly
  1746.      similar to Protracker modules, but support two effects per channel.
  1747.      "UltraTracker" was written by MAS of Prophecy, a.k.a. Marc Andre
  1748.      Schallehn, and released in 1993.
  1749.  
  1750. `load_uni'
  1751.      This loader recognizes "UNIMOD" modules. This is the internal
  1752.      format used by MikMod and APlayer. Use of this format is
  1753.      discouraged, this loader being provided for completeness.
  1754.  
  1755. `load_xm'
  1756.      This loader recognizes "FastTracker 2" modules. This format was
  1757.      designed from scratch, instead of creating yet another Protracker
  1758.      variation. It was the first format using instruments as well as
  1759.      samples, and envelopes for finer effects.
  1760.      FastTracker 2 was written by Fredrik Huss and Magnus Hogdahl, and
  1761.      released in 1994.
  1762.  
  1763. 
  1764. File: mikmod.info,  Node: Sample Loaders,  Next: Driver Reference,  Prev: Module Loaders,  Up: Loader Reference
  1765.  
  1766. Sample Loaders
  1767. --------------
  1768.  
  1769.    Currently, the only file type than can be loaded as a sample is the
  1770. RIFF WAVE file. Stereo or compressed WAVE files are not supported yet.
  1771.  
  1772. 
  1773. File: mikmod.info,  Node: Driver Reference,  Next: Network Drivers,  Prev: Sample Loaders,  Up: Library Reference
  1774.  
  1775. Driver Reference
  1776. ================
  1777.  
  1778. * Menu:
  1779.  
  1780. * Network Drivers::
  1781. * Hardware Drivers::
  1782. * Disk Writer Drivers::
  1783. * Other Drivers::
  1784.  
  1785. 
  1786. File: mikmod.info,  Node: Network Drivers,  Next: Hardware Drivers,  Prev: Driver Reference,  Up: Driver Reference
  1787.  
  1788. Network Drivers
  1789. ---------------
  1790.  
  1791.    These drivers send the generated sound over the network to a server
  1792. program, which sends the sound to the real sound hardware. The server
  1793. program can be on the same machine than your program, but MikMod does
  1794. not have access to the hardware. Network drivers only support software
  1795. mixing.
  1796.  
  1797. `drv_AF'
  1798.      This driver works with the "Digital AudioFile" library.
  1799.      Start the server on the machine you want, set its hostname in the
  1800.      `AUDIOFILE' environment variable, and MikMod is ready to send it
  1801.      sound.
  1802.  
  1803. `drv_esd'
  1804.      This driver works with the "Enlightened Sound Daemon".
  1805.      Start the esd daemon on the machine you want, set its hostname in
  1806.      the `ESPEAKER' environment variable, and MikMod is ready to send
  1807.      it sound.
  1808.  
  1809.